Not sure I agree with the move of the syntax.md file. It's a documentation file about how to write specs, which applies to files that exist in the specs, so why should be in a different repo? How is it even related to "tools", which are an implementation detail of the spec build process?

How is it even related to "tools", which are an implementation detail of the spec build process?

The syntax.md file documents the input format of the tool that generates the markdown output of the spec. IMHO the whole semantic_conventions/ top-level directory is as much an implementation detail of the spec as the semantic conventions generator tool.

The reason for the move was described in open-telemetry/build-tools#53, and it's a very practical one: As soon as you change the input format of the tool, you need to update syntax.md. If you have both in the same repository, you can update them in one PR and the changes to syntax.md also serve as documentation to the changes in the implementing Python code.

Since we have the (now required) semantic-conventions check as part of every PR, you can't even write anything in the YAML that the tool doesn't support, even if it would maybe make sense conceptually, so the tool is a quite important "implementation detail" 😃

Heads-up: I created a PR to update syntax.md in the build tools, since it was not up to date with some recent additions to the tool. I also documented features that were there from the beginning but are not currently used in the spec (with a warning): open-telemetry/build-tools#56